Celestin Apprentice 5

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / C / Snippets / ShowInitAndName / ShowInitAndName.h < prev next >

Wrap

Text File | 1996-01-12 | 19.3 KB | 471 lines | [TEXT/CWIE]

/*************************************************************************************************** ShowInitAndName ShowInitAndName includes routines to display an icon and title at startup, as well as a Notification Manager routine for displaying error messages to the user. A few bonus support routines are also available for Pascal & C string copying, along with easy calls for information regarding the System Software and Color Quickdraw. These routines make writing cool System Extensions (INITs) a whole lot easier. I hope you’ll find them to be easy to program and stable under all conditions. Please donate bug reports, feature requests, and other improvements to: Storm Impact, Inc. 316 Nottingham Ave. Glenview, IL 60025-5022 USA StormImpac@aol.com What Makes These Routines Easy To Use? -------------------------------------- • You MAY pass nil for ANY pointer in ANY routine without bombing or corruption. (If you don’t supply enough information, the routine will simply do nothing.) • You DON’T NEED TO INITIALIZE any toolbox routine (or port or whatever) before calling ShowInitAndName. It does that work for you. • You DON’T NEED TO DETERMINE whether the appropriate Mac or System Software is installed. (Each routine does its own checking of the environment.) • You DON’T NEED TO INCLUDE additional libraries or source code. It’s all here. (Of course, most compilers require the inclusion of MacTraps or InterfaceLib.o for any Mac OS project) • You MAY use none, one, or all of these routines, in any order. It’s up to you. • You MAY read the “Inside Macintosh”-type documentation for each routine. (The documentation is at the start of each routine within the “.c” file itself.) • You MAY examine the ShowInitAndName example source code for a number of examples of these routines in action. • You MAY compile these routines to PowerPC or 680x0 targets. There’s no assembly or processor hacks. • You MAY use 'cicn' resources for ShowInitAndName, or you may use the more popular 'icl8', 'icl4', and 'ICN#' resources. What If Icons Are Shown Differently In FUTURE Systems? ------------------------------------------------------ If available, these routines call a System-based ShowInit instead of showing the icon and name themselves. If a future programmer comes up with a completely new way of showing inits, or if a user likes the old ShowInit style, these routines automatically yield to the System. Also, all calls to the Notification Manager are made with nmRefCon set to a particular constant ('SIaN'). If a future programmer wishes to display init error messages DURING startup, or place the error messages in a log file, there will be a constant to patch on. Version History: ---------------- 96/01/12 v1.0.0 David Cook First released version If you’d like, send us email at “StormImpac@aol.com”, and we’ll be glad to email you the latest release version of these routines. Remember, it’s your responsibility to completely test these routines to make sure the version you are using meets your needs and your customer’s needs. Requirements: ------------- Compiled using: Metrowerks release 7 (but should also work with Think C 8 (what’s that?) or better.) Resulting object: System Software 6.0 or better Mac Plus to the newest (including the Power Macintosh w/PCI models). (Technically, I can’t see any reason why ShowInitAndName won’t run in earlier versions of System Software prior to 6.0, but I haven’t tried it.) Last Minute Notes: ------------------ • Old B&W-Quickdraw Macs are hard coded to a screen size of 512x342, which means this code may not wrap icons correctly on a Lisa or MacXL. • Non-32x32 'cicn' resources aren’t directly supported. However, I don’t know of anyone that uses 'cicn's that aren’t the standard 32 pixels by 32 pixels. • Some old extension “managers” and “wrappers” were designed to forcibly override the inits’ icon positioning and drawing routines. Although my code attempts to accept the overridden drawing position, many old managers don’t provide feedback to their overrides. In the case of Now Startup Manager 3.0.2 (as an example), the extension name may be drawn far below the icon, because Now Startup silently moves the icon up without any way for my code to discover the change. Thanks: ------- Thanks to the authors of “ShowInit.a”: Paul Mercer, Darin Adler, and Paul Snively, from an idea by Steve Capps. Not only were they the first to show init icons at startup, but they made their code publicly available so that all Macintosh developers could gain the ability. They set the standard by which all future routines must live up to. Bibliography: ------------- Bassindale, Brian W. “ShowINITIcon1.1.p”, Developer’s Forum. America Online, Vienna, VA., October 1995 Beard, Patrick, and James W. Walker. “ShowIconFamily.c”, Developer’s Forum. America Online, Vienna, VA., October 1995 Faigle, Chris. “Animated SI 1.0a2.c”, Developer’s Forum. America Online, Vienna, VA., October 1995 Grant, Dair. “ShowIcon.c” from Extension Shell 1.3, Developer’s Forum. America Online, Vienna, VA., October 1995 Lewis, Peter, and James W. Walker. “ShowInitIcon.c” [Not related to Eric Shapiro’s of the same name], Developer’s Forum. America Online, Vienna, VA., October 1995. Mercer, Paul, Darin Adler, and Paul Snively. “ShowINIT.a” [7/14/88], CD Slickers, Tool Chest, Developers CD Series. Apple Computer, Inc., Cupertino, CA., August 1993. †Mercer, Paul, Darin Adler, Paul Snively, Frédéric Miserey, and Alex Rosenberg. “ShowInit.a” [3/27/90], Tool Chest, Developers CD Series. Apple Computer, Inc., Cupertino, CA., May 1995. †Mercer, Paul, Darin Adler, Paul Snively, Brad Lowe. “ShowINIT.a” [1/21/91], A ROM With a View, Developers CD Series. Apple Computer, Inc., Cupertino, CA., September 1992. †Mercer, Paul, Darin Adler, Paul Snively, Brad Lowe, and MK. “ShowINIT.a” [9/9/92], Reference Library, Developers CD Series. Apple Computer, Inc., Cupertino, CA., September 1995. Pottier, François, and Peter N. Lewis. “ShowInit-75.p”, Reference Library, Developers CD Series. Apple Computer, Inc., Cupertino, CA., September 1995. Shapiro, Eric, and James W. Walker. “ShowInitIcon.c” [Not related to Peter Lewis’s of the same name], Tool Chest, Developers CD Series. Apple Computer, Inc., Cupertino, CA., May 1995. Walker, James W., and Patrick C. Beard. “ShowIcon7.c”, Developer’s Forum. America Online, Vienna, VA., October 1995 Walker, James W., Patrick C. Beard, and Brian Bechtel. “ShowIcon7.c”, Tool Chest, Developers CD Series. Apple Computer, Inc., Cupertino, CA., May 1995. †WARNING: There are a number of versions of “ShowINIT.a” which took different branches because several authors all started from Paul Mercer’s 7/14/88 source code. Although named identically, these branch versions of “ShowINIT.a” are very different from each other. Beware! The Vertical Position Problem: ------------------------------ The HORIZONTAL position (and a checksum for safety) of an init’s icon and text is stored in the last 4 bytes of the current application’s filename, as has been the method since “ShowInit.a” 7/1/87. Since there is no current application at startup, the end of the CurApName has continued to be an acceptable storage location. ShowInit.a: “a GREAT place to store 4 bytes (it was Darin's idea)” BUT, OH NO! Two different programmers, at around the same time, came up with two different methods for storing vertical positions to supplement ShowInit’s horizontal position. Starting with Frédéric Miserey’s version of “ShowInit.a” 11/25/89, the VERTICAL position (and a checksum for safety) is stored in the 4 bytes immediately before the horizontal location in the current application’s filename. This is the same method that we use in ShowInitAndName. However, James W. Walker’s pre-1994(?) routines use a different approach to the VERTICAL position. Those routines allow the stored horizontal position to exceed the width of the screen, but then “wrap” the horizontal position up to the next screen row, and the next row, and so on. This seemed like a nice idea, because it used 4 bytes fewer of CurApName space. Unfortunately, anyone using Miserey’s approach prevents Walker’s “wrap” method from working. Have you ever seen an icon appear on the 2nd row, then an icon on the 1st row, and then an icon back on the 2nd row -- in correct horizontal order? Well, then you observed ShowInit 1989+ followed by any other method, followed by ShowInit 1989+. To discover the most popular init method, I inspected most of the INIT resources I could find. Here are some of the results: Doesn’t read or store vertical position: Speech Manager 1.4 - An IconDispatch based routine Sound Manager 3.1 - An IconDispatch based routine AppleScript 1.1 - “ShowInit.a” 7/14/88 [ Which Paul Mercer labeled 7/15/88 ] On Location 2.0.1 - “ShowInit.a” 7/14/88 [ Which Paul Mercer labeled 7/15/88 ] DebuggerINIT 1.1.2 - “ShowInit.a” 7/14/88 [ Which Paul Mercer labeled 7/15/88 ] QuicKeys 3.0.1 - “ShowInit.a” 7/14/88 [ Which Paul Mercer labeled 7/15/88 ] Video Startup 1.3.1 - “ShowInit.a” 7/14/88 [ Which Paul Mercer labeled 7/15/88 ] Reads and stores vertical position: ATI Displays 1.0 - An IconDispatch based routine QuickTime 2.0.9 - A custom CopyMask and clut based routine Capture 4.0.2 - A CopyMask and clut based routine AppleGuide 1.2.7 - A CopyMask and clut based routine Disinfectant 3.6 - “ShowInit.a” 11/25/89 Now Utilities 5.0.1 - “ShowInit.a” 11/25/89, Modified by jbx 7/13/92 Turbo Mouse 4.0.2 - “ShowInit.a” 03/27/90 PC Exchange 2.0.5 - “ShowInit.a” 03/27/90 ColorSync 2.0 - “ShowInit.a” 03/27/90 The biggest shock is that in System 7.5.2 Apple itself uses at least 4 different versions of routines for showing inits at startup! And, some of those routines fail on the second row (or any vertical positioning). Names and trademarks mentioned throughout this code are not associated with David Cook or Storm Impact, Inc. My analysis of their code could be wrong; it’s only an educated guess. Legal Information: ------------------ ShowInitAndName.c (including all C, headers, examples, and resource files) is Copyright © 1996 by Storm Impact, Inc. All Rights Reserved. Storm Impact and the Storm Impact logo are trademarks of Storm Impact, Inc. THESE ROUTINES ARE AS-IS. THEY MAY CONTAIN SIGNIFICANT BUGS. You may include any or all of these routines as compiled executables, free of charge from us, and you may also distribute COMPLETE, UNMODIFIED copies of the source code, free of charge from us. In exchange, you assume all liabilities, risks, and costs associated with using or distributing these routines, and you agree to provide us a free copy of your complete product within thirty (30) days of publication or public release. (If your product is not offered publicly, you don’t have to send us a copy.) If you need other legal arrangements, custom modifications, or the latest version, please feel free to contact us at the address at the beginning of this document. The artwork and icons included in the examples may not be used or distributed except as part of the complete and unmodified source code. Software Of The Month Club is prohibited from distributing any and/or all of this under any and/or all circumstances. So there. Enjoy! David Cook Storm Impact, Inc. */ #include <Icons.h> /* Here are some definitions if your compiler doesn’t have them */ /* #define true 1 #define false 0 #define LMGetCurApName() ((StringPtr) 0x0910) #define LMSetCurApName(pascalStringPtr) () */ #define kIconResourceIDNone 0 /* Pass this whenever you don’t want to display an icon but the routine calls for an icon resource id. */ /************ This routine is all you need to show an init with a C filename ***********/ OSErr ShowInitAndName ( short iconResourceID, char *extensionNameInCFormat, char *statusMessageInCFormat, OSErr errorEncounteredIfAny, Boolean allDone ); /************ Or, use this routine if you have a Pascal format filename ***********/ OSErr ShowInitAndPascalName ( short iconResourceID, StringPtr extensionNameInPascalFormat, StringPtr statusMessageInPascalFormat, OSErr errorEncounteredIfAny, Boolean allDone ); /********************** BONUS ROUTINES *************************** /* This routine is all you need to display a c-format string alert message to the user */ OSErr NotificationManagerMessage ( char *messageInCFormat ); /* Simple environment checking routines which you may (or may not) find useful in your init */ Boolean IsColorQuickdrawAvailable ( void ); long GetSystemVersion ( void ); /* Pascal and C String routines which you may (or may not) find useful in your init */ unsigned long GetLengthOfCStringWithLimit ( char *pointerToCString, unsigned long countNoMoreThanThisManyCharacters ); void CopyCStringFromPascalStringWithLimit ( char *pointerToDestinationCString, StringPtr pointerToSourcePascalString, Byte copyNoMoreThanThisManyCharacters ); /* All of the above routines have “Inside Macintosh”-like documentation at the start */ /* of each routine within the “ShowInitAndName.c” source file code itself. Take a look! */ /* ATTENTION: The rest of this header file contains internal routines and constants. */ /* You may read it if you’d like, of course. */ #if PRAGMA_ALIGN_SUPPORTED #pragma options align=mac68k #endif typedef struct { char privates[76]; long randSeed; BitMap screenBits; Cursor arrow; Pattern dkGray; Pattern ltGray; Pattern gray; Pattern black; Pattern white; GrafPtr thePort; long setTheLocalA5ToHere; } QDGlobalsPlusAStartForTheLocalA5; #if PRAGMA_ALIGN_SUPPORTED #pragma options align=reset #endif #define gestaltShowInitAndName 'SIaN' #define kNotificationSentByShowInitAndName gestaltShowInitAndName typedef pascal OSErr (*ShowInitOverrideProcPtr)(short iconResourceID, char *extensionNameInCFormat, char *statusMessageInCFormat, OSErr errorEncounteredIfAny, Boolean allDone, long reservedForFutureExpansion ); #if GENERATINGCFM typedef UniversalProcPtr ShowInitOverrideUPP; #else typedef ShowInitOverrideProcPtr ShowInitOverrideUPP; #endif enum { showInitOverrideProcInfo = kThinkCStackBased | RESULT_SIZE(SIZE_CODE(sizeof(OSErr))) | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short))) | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(char*))) | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(char*))) | STACK_ROUTINE_PARAMETER(4, SIZE_CODE(sizeof(OSErr))) | STACK_ROUTINE_PARAMETER(5, SIZE_CODE(sizeof(Boolean))) | STACK_ROUTINE_PARAMETER(6, SIZE_CODE(sizeof(long))) }; #if GENERATINGCFM #define NewShowInitOverrideProc(userRoutine) \ (ShowInitOverrideUPP) NewRoutineDescriptor((ProcPtr)(userRoutine),(showInitOverrideProcInfo),(GetCurrentArchitecture())) #else #define NewShowInitOverrideProc(userRoutine) \ ((ShowInitOverrideUPP) (userRoutine)) #endif #if GENERATINGCFM #define CallShowInitOverrideProc(userRoutine, iconResourceID, extensionNameInCFormat, statusMessageInCFormat, errorEncounteredIfAny, allDone, reservedForFutureExpansion) \ CallUniversalProc((UniversalProcPtr)(userRoutine),(showInitOverrideProcInfo),(iconResourceID),(extensionNameInCFormat), (statusMessageInCFormat), (errorEncounteredIfAny), (allDone), (reservedForFutureExpansion)) #else #define CallShowInitOverrideProc(userRoutine, iconResourceID, extensionNameInCFormat, statusMessageInCFormat, errorEncounteredIfAny, allDone, reservedForFutureExpansion) \ (*(userRoutine))((iconResourceID),(extensionNameInCFormat),(statusMessageInCFormat),(errorEncounteredIfAny),(allDone),(reservedForFutureExpansion)) #endif #define kShowInitHasOverridden_NoNeedForLocalCode 1 #define kHeightOfIcon 32 #define kWidthOfIcon 32 #define kMinimumPixelDepthToDrawColorIcons 4 #define kByteOffsetToICNMask 128 /* offset to mask in ICN# resource */ #define kBitmapRowBytesForBWIcon (32/8) #define kTextCStringFont geneva #define kTextCStringFontSize 9 #define kTextCStringAlignment teCenter #define kTextCStringFace normal #define kTextCStringMaximumNumberOfCharacters 255 #define kTextCStringHeight 12 #define kTextCStringHorizontalBorderWhiteSpace 4 /* Two pixels on each side */ #define kShowInitMarginForMainScreenLeft 8 #define kShowInitMarginForMainScreenRight 8 #define kShowInitMarginForMainScreenTop 8 #define kShowInitMarginForMainScreenBottom 8 #define kHorizontalMarginBetweenShowInits 8 #define kVerticalMarginBetweenShowInits 8 #define kMinimumVerticalSizeOfShowInit ( kHeightOfIcon + kTextCStringHeight ) #define kMaximumTotalPixelWidthOfAShowInit 410 #define kChecksumStorageConstant 0x1021 #define kOffsetFromCurApNameToStoredVerticalChecksum 24 #define kOffsetFromCurApNameToStoredVertical 26 #define kOffsetFromCurApNameToStoredHorizontal 28 #define kOffsetFromCurApNameToStoredHorizontalChecksum 30 #define kDefaultHorizontalOffsetFromLeftOfMainScreenIfHorizontalChecksumIsWrong 8 #define kDefaultVerticalOffsetFromBottomOfMainScreenIfVerticalChecksumIsWrong 40 #define kNotificationManagerMinimumSystemRequired 0x0600 typedef struct { NMRec notificationRecord; unsigned char *notificationPascalString [ ]; } NMRecAndPascalStringCombinedRecord; void DrawTextCString ( char *pointerToTextCString, Rect *pointerToDestinationRect ); short GetPixelWidthOfTextCString ( char *pointerToTextCString ); long GetMainScreenPixelDepth ( void ); void GetMainScreenRect ( Rect *mainScreenRectPtr ); Boolean IsPlotIconIDAvailable ( void ); OSErr DrawIcon ( short iconResourceID, short pixelDepthOfScreenToDrawOn, Rect *pointerToDestinationRect ); void DrawCrossOut ( Rect *pointerToDestinationRect, short pixelDepthOfScreenToDrawOn ); void AdvanceShowInit ( short byHorizontalAmount ); Boolean CorrectShowInitHorizontalAndVerticalIfNotOnMainScreen ( short *pointerToHorizontal, short horizontalSizeOfThisShowInit, short *pointerToVertical, short verticalSizeOfThisShowInit ); void LMGetShowInitHorizontalAndVertical ( short *pointerToHorizontal, short *pointerToVertical ); void LMSetShowInitHorizontalAndVertical ( short horizontal, short vertical ); short CalculateHorizontalOrVerticalStorageChecksum ( short horizontalOrVerticalValue );